Amiga Collections: Scope/Scope Disk #112 (199x)(Scope PD)(US)[WB].zip/Scope Disk #112 (199x)(Scope PD)(US)[WB].adf/Conman/ConMan.doc

Text File | 1990-01-24 | 25KB | 454 lines

                               ConMan V1.3c
               Copyright © 1987,1988,1989 by William S. Hawes

   ConMan is a replacement console handler that provides line editing and
   command history for any software that uses CON: windows.  It runs under
   AmigaDOS V1.2 and later, and is completely transparent to other software.
   After ConMan has been activated, all CON: windows opened by AmigaDOS will
   automatically use the ConMan handler.  This includes the console windows
   opened by NEWCLI as well as any data input/output windows that your other
   software may use.

   Features new to ConMan V1.3c include the CNN: handler for invisible,
   non-blocking type-ahead, the CNX: (extensible) handler for use of the
   serial device as a console, improved editing of long lines, and support
   for superbitmap windows.  ConMan also now supports deferred opening, in
   which the console window is not actually opened until a read or write
   request is received.

   As was the case with prior releases, ConMan is distributed as shareware
   (user-supported software), and I'm pleased to report that the rate of
   contributions has increased since the last release.  Shareware is a
   welcome alternative to the high costs of commercial software, and I hope
   that you'll do your part to support ConMan and other shareware products.


                          ----- Line Editing -----
   ConMan allows you to edit the active (command) line using the left- and
   right-arrow keys for cursor positioning.  The shifted left-arrow key
   skips to the beginning of the current or previous word, and the shifted
   right-arrow key skips to the start of the next word.

   ConMan supports both insert and overstrike editing modes.  The CTRL-A
   key toggles between the two modes, and the CTRL-^ key unconditionally
   selects insert mode.  The default input mode is insert, but you can set
   the global -o flag to select overstrike mode.  The input mode normally
   reverts to the default mode each time you press RETURN, but the global
   -s ("sticky") flag will cause the mode to remain set until you change it
   explicitly.

   You can select insert or overstrike mode when you first install ConMan,
   and can change it at any time using the SetCMan command utility.  Try
   experimenting to see which input mode you like best, but note that the
   input modes are global and therefore apply to ALL ConMan windows.  Refer
   to the paragraph on installation for a list of the global option flags.

   There are several keys that can be used to delete characters, words, or
   the entire line.  The DEL key deletes the character under the cursor,
   and the BACKSPACE key deletes the character to the left of the cursor.
   CTRL-Y deletes from the cursor position to the end of the line, and
   CTRL-U deletes from the cursor to the start of the line.  CTRL-X deletes
   the entire line, in keeping with the default CON: device.

   Function keys F7 and F8 can be used to delete words in the backwards and
   forwards direction, respectively.  They work just like the shifted left-
   and right-arrow keys except that the characters are deleted.

   CTRL-Z deletes both the current line and any lines that have been typed
   ahead (but not yet read); this is very handy if you want to completely
   abandon all typed-ahead lines.  CTRL-R provides a less drastic recall
   by posting the typed-ahead lines back to the command line.  CTRL-W clears
   the entire window and then redisplays the active line.

   The Undo Buffer.
   Suppose that you're editing a line and you accidentally hit the up- or
   down-arrow key.  You've just lost the line, right?  Not at all --- just
   press the CTRL-- (control-minus) key and the former line will be posted
   back to the command line, with the cursor right where you left it!

   There is no limit to the number of lines that can be undone, but only
   lines that have been changed are added to the undo buffer.  All "undo"
   lines are discarded when you finally enter RETURN.

   Flow Control.
   CTRL-S and CTRL-Q have been implemented to hold and release the screen
   output, respectively.  After pressing the CTRL-S key, all output to the
   window will be held until you release it with a CTRL-Q.  ConMan will
   "beep" the display if you try to type with CTRL-S in effect, in order
   to provide some visual indication that output is held.

   End-of-File.
   ConMan recognizes the CTRL-\ character as an end-of-file and sends a
   zero-length block to the task reading from the handler.  CTRL-\ can be
   used to terminate a copy operation.

   All characters not explicitly required for editing purposes are passed
   on to the command line.  In order to provide a consistent display,
   characters that might cause interference with the display (like CTRL-L)
   are rendered as a caret (^) followed by the uppercase alphabetic
   character.  The CTRL-N (shift-in) and CTRL-O (shift-out) characters are
   supported by ConMan; these are non-printable by themselves, but serve
   to select and unselect the alternate character set.  Miscellaneous
   non-printable characters are displayed as a hash mark.

   ConMan now allows control sequences can be entered incrementally.  For
   example, entering ESC, [, 0, and ~ will simulate the effect of an F1 key.


                          ----- Command History -----
   ConMan "remembers" the commands that you type and lets you recall them
   sequentially using the up- and down-arrow keys.  If you go past the line
   you want, the down-arrow key will retrieve the next (more recent) line.
   The shifted up-arrow key recalls the oldest line, and shifted down-arrow
   recalls the most recent line.  The CTRL-B key clears the history buffer.

   The history buffer is organized as a fixed-length memory pool with a
   default length of 488 bytes.  New lines are inserted at one end, and
   the oldest lines are pushed off the other end to make room.  The number
   of lines that can be saved depends on their lengths, but is generally in
   the range of 25 to 30.  The default size can be changed when you install
   ConMan by using the -b option followed by the desired size in bytes.
   For example, the command "conman -c -b1000" would install ConMan with a
   1000-byte history buffer.

   ConMan maintains the history in one of two modes.  In the default mode,
   recalled lines are not reentered into the history buffer unless the line
   was "touched," and the history index pointer is left positioned at the
   retrieved line.  This mode is convenient if you often go back into the
   buffer to retrieve sequences of commands.

   In "true history" mode, every line is reentered into the history buffer,
   even if it wasn't modified after being recalled.  The history pointer is
   always reset (to the most recent line) whenever a line is added to the
   buffer.

   The history mode can be selected when ConMan is installed or by using the
   "SetCMan CON: -t" command.  Note that ConMan checks for duplicate entries
   irrespective of whether standard or "true" history is selected.  If the
   current line matches the previous line entered, the line is not reentered.

   Minimum Line Length.
   You can define a minimum line length to be saved in the history buffer by
   using the -LNNN option.  The number following the -L is the limit at or
   below which lines will not be saved; the default value is 0.  For example,
   "conman -c -L2" will ignore lines of 2 or fewer characters.

   Wrap-Around History.
   If you prefer to maintain the command history as a circular buffer rather
   than as a stack, try setting the -wrap option with ConMan or SetCMan.
   The index will "wrap-around" when it hits the top or bottom of the stack.

   Versions 1.1 and later of ConMan include a command called "History" to
   save, load, or display the history buffer.  Refer to the "Extras.doc"
   file for more information.


                          ----- Function Keys -----
   ConMan has several additional editing functions and window control options
   that use the function keys.

   Key F1 shrinks ("iconifies") the window to its minimum size, and key F2
   "zooms" the window to its maximum size (usually the entire screen.)  Both
   keys act as toggles, and shrunken windows may be zoomed (and vice-versa.)
   ConMan V1.3 provides a minor enhancement to the zoom feature:  if the
   window is not exactly at the top of the screen when F2 is hit, it will be
   positioned one pixel down from the top, rather than right at the top.
   This allows you to slide the screen even if the window covers most of it.
   If the window was opened without a sizing gadget, neither F1 or F2 will
   have any effect.

   Keys F5 and F6 are used to search for commands.  If you type a partial
   command line and then press F6, ConMan searches in the up-arrow direction
   for a line matching up to the cursor position.  You can move the cursor
   to the right to constrain the search.  Key F5 works similarly in the
   down-arrow direction.

   Keys F7 and F8 delete words in the backwards and forwards direction.
   They operate just like the shifted left- and right-arrow keys, except
   that the words are deleted rather than just skipped over.

   Function key F9 moves the screen to the front or back of the display,
   and F10 moves the window to the front or back.  Both keys act as toggles
   provided that you don't deactivate the window or screen.  These keys are
   useful when you're working with multiple windows or screens and need to
   peek at the one in back.


                        ----- Window Definitions -----
   ConMan accepts the standard AmigaDOS window specifications.  For example,
   "CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
   beginning in position (160,50).  The numeric parameters are truncated
   against the maximum screen size, so a larger-than-normal window may be
   safely specified (for those of you using "morerows").  The default size
   is the full screen width and height.  ConMan sets the minimum window size
   to allow room for the close gadget and depth gadgets.

   Various Intuition options and gadgets can be selected by including a list
   of attributes after the window title.  Here's how it works:  put another
   slash ("/") after the window title, and follow it with any of the
   attribute options listed below.

      Option Character                 Default Value
      ----------------                 -------------
      A <==> Activate                  Activated
      B <==> BackDrop                  Not a backdrop
      C <==> Close gadget              No close gadget
      D <==> Depth gadgets             Depth gadgets
      M <==> Move (drag) gadget        Drag gadget
      N <==> NoBorder                  Border (sorry, "B" was used)
      R <==> Refresh (SMART/SIMPLE)    Smart refresh
      S <==> Sizing gadget             Sizing gadget
      Z <==> Zero-Zero                 Not a GZZ

   Each option character will TOGGLE the corresponding window attribute,
   so if you include an option twice, it will cancel the effect.  Any
   unrecognized attribute characters are ignored, and the closing slash is
   optional.  My apologies to those who wanted a slash in the title.

   Examples: CON:10/10/300/100/Behind/nb/   a borderless backdrop window.
             CON:10/10/300/100/Fixed/acm    a nonactivated window, with a
                                            close gadget, that won't budge.

   You can select the colors for the window's titlebar area by appending a
   '/' to the attribute list and specifying the "detail pen" and "block pen"
   color values; the color numbers are listed below.

      Pen Number  Color
      ----------  -----
          0       Blue
          1       White
          2       Black
          3       Red

   For example, "CON://640/100/Colors!/ac/23" would specify a window with
   black letters (the detail pen) on a red titlebar (the block pen).


                          ----- Installation ----
   To install ConMan you'll need to copy a few files to your system disk,
   but don't worry --- they're all small.  Install the file "Conhandler"
   in your L: directory, to keep those bigger handlers company.  Then copy
   the file "conhandler.library" into your LIBS: directory.  Now copy the
   commands "ConMan", "SetCMan", and "History" to your C: directory; the
   other command programs are optional.  The included "ExecuteMe" file will
   handle the installation if you'd rather do it automatically.

   If you received ConMan in the form of an ARCed file, first deARC it and
   then rename "conlib.lib" to "conhandler.library", or use the provided
   "ARCInstall" script to copy the files.

   Once these files have been installed, issue the command "conman -c" to
   activate the handler.  After you've activated ConMan, open a CLI window
   using NEWCLI and check to make sure that the new window has line editing
   and command history.  Once everything is working properly, you should
   place the "conman -c" command in your startup-sequence so that it's always
   available.

   NOTE:  ConMan affects only those windows opened AFTER you activate it!
   It would be very impolite indeed to pull the old handler out from under
   the existing console windows.

   You can specify several command line arguments with the ConMan command:

      Code     Action
      ------   ------
      -bNNNN   select buffer size NNNN bytes
      -c       install as CON: (the default)
      -lNNN    minimum length to save
      -o       select overstrike mode
      -r       install as RAW:
      -s       select "sticky" mode
      -t       maintain "true history"
      -w       select "wrap-around" history

   These command options can appear in any order and remain in effect until
   you reboot the computer.  The options established by the ConMan command
   are the global defaults inherited when each device is opened.  Subsequent
   changes must be made using the SetCMan command described below.

   A separate utility program called "SetCMan" has been provided to modify
   the global options or device attributes.  You can use SetCMan to change
   the -o, -s, -t, or -w options at any time, and the device attributes -d
   (deferred opening) and -n (non-blocking) can be set if no devices of the
   specified type are open.  To set the options on a device-by-device basis,
   a device name must supplied with the command, as the examples illustate.
   Examples: setcman ?            ; displays the template
             setcman -o -s -t     ; overstrike, sticky, true history
             setcman CON: -n      ; set CON: for non-blocking
             setcman CNC: -d -w   ; CNC: deferred opening with wrap history

   If you usually operate from Workbench and only occasionally need a CLI,
   you can activate ConMan by using the icons.  First double-click on the
   "LoadLib" icon to load the conhandler library, and then activate ConMan
   by double-clicking the "ConMan" icon.  The next CLI you open should now
   have the line editing and command history provided by ConMan.


                          ----- Distribution -----
   This program is distributed as shareware (user-supported software) to
   Amigoid life-forms everywhere!  Make sure your friends get a copy.
   Your contributions are greatly appreciated and will help me maintain
   ConMan as well as develop new products.  Send all correspondence to:

         By Mail:                      By Telephone or EMail:
         -----------------             ------------------------------
         William S. Hawes              Phone: [phone]
         P.O. Box 308                  BIX: whawes
         Maynard, MA 01754             CIS: 72230,267
         USA                           PLINK: whawes

   The suggested contribution is $10 (based on an earlier survey), but any
   amount is welcome.  The number of registered ConMan users has increased
   significantly since the last release, but is still far below what would
   be expected for a comparable commercial product.

   Commercial vendors are welcome to include ConMan with their products,
   provided that it's noted as being shareware and that the documentation
   accompanies the software.


                          ----- Other Products -----
   I have a couple of other products available commercially.   ARexx and
   WShell can be found at better dealers**, or you can order them directly
   from me at the above address.

   ARexx is a multitasking implementation of the REXX language, a high-level
   interpreted language designed for macro-processing.  ARexx has become the
   de facto standard for inter-program communications and can be used as the
   macro language for any software package that includes an ARexx interface.
   It's both powerful and easy-to-learn, and is well documented in a 150-page
   manual.  ................................. Only $49.95 (plus $2 shipping)

   WShell is a much-enhanced but highly compatible CLI replacement that
   offers aliases, built-in and resident commands, concurrent command piping
   (as in pgm1 | pgm2 | ... | pgmN), extended prompt/window titlebar fields,
   transparent support for REXX macro programs, an "implicit" CD command,
   script-bit support, and lots of other features.  Isn't it time you put
   some mussel into your command environment?  Just 50 clams (+ $2 shipping)

   ** better dealers are those that stock ARexx and WShell.


                          ----- Further Notes -----
   ConMan also accepts window specifications in the form "CON:w20480", where
   the hex digits following the "w" are the absolute address of an Intuition
   window pointer.  This allows you to attach a console handler to a window
   in a multitasking-safe way (unlike the methods that require setting a
   field in the DOS device list).  If you're writing in C, you could use
   the following sequence to open a window and attach a DOS console to it:

         window = OpenWindow(&newwindow);   /* get a window          */
         sprintf(buffer,"CON:W%x",window);  /* build the name string */
         file  = Open(buffer,MODE_OLDFILE); /* open a console stream */

   You can open a console window on a custom screen by passing the hex
   address of the screen preceded by an "S" in the specification string,
   as in "CON:S123abc/10/10/300/100/MyWindow."  ConMan will accept "S*" as
   a shorthand notation for the frontmost screen, so a specification like
   "CON:S*/0/0/300/100/Front" would open on whichever screen was in front.
   Watch out for using S* in a double quoted-string, though, since the * is
   the default AMigaDOS escape character.  If your console specification
   includes spaces and thus needs to be quoted, you'll need to use S** as
   in this example:
     1> newcli "CON:S**/0/0/640/100/My Window/a/23"

   In addition, ConMan now supports superbitmap windows as well.  The bitmap
   structure is passed as a "B" followed by the hex address, as for example
   "CON:B123ABC/0/0/300/100/Super!".  The console device currently has some
   bugs related to using superbitmaps (for example, the cursor disappears),
   but this feature may be handy anyway.


   Other Names.
   ConMan is actually several DOS handlers rolled into one, and it selects
   the desired mode of operation by looking at the name used to open it.
   The four special names recognized are CND:, CNN:, CNX:, and PIP:, and all
   other names are considered equivalent to CON:.

   In order to use ConMan under any name other than CON:, you'll need to add
   one or more of the supplied mountlist entries to your DEVS:mountlist file
   and then issue the "mount" command.  For example, to define ConMan as the
   CNC: device, add the CNC: entry to DEVS:mountlist and issue "mount CNC:".
   Once you've done this, you can get a ConMan window by specifying a name
   like CNC://640/100/MyWindow.  This allows the CON: definition to be left
   intact, in case there are any incompatibilities between ConMan and your
   existing software (but please let me know of any problems!)

   Warning: DO NOT USE the ARP mount command to mount ConMan --- it has a
   known bug that causes the console handler to open up in RAW mode.

   The CND: handler uses the deferred opening mode by default.  Deferred
   opening means that the window is not actually opened until it is read
   from or written to; this provides a cosmetic improvment for programs
   that need a window to report error messages.

   The CNN: handler, new to V1.3, operates in a mode that allows invisible
   (non-blocking) type-ahead.  After the line you enter has been read, any
   further input is not displayed until the command shell (or other software)
   again reads from the console.  This gives unimpeded access to whatever
   software is writing to the console.
   Example:  NewCLI "CND://640/100/VAX Head!"

   The CNX: handler is also new to V1.3, and provides extensibility by
   allowing you to specify any EXEC-level device for the console display.
   The display device name and unit are passed immediately following the
   handler name, as in "CNX:device-name/unit".  For example, you could
   specify the serial device as "CNX:serial.device/0", providing an AUX:
   handler with full line editing and command history.  The display device
   must support the standard ANSI control sequences on read and write.
   Example:  NewCLI CNX:serial.device/0

   ConMan is also a pipe-handler responding to the name PIP:NNNN, where
   NNNN is the "capacity" of the pipe.  It must be opened using a private
   packet called ACTION_DOUBLE (value 2000L), and the filehandle you get
   from a call to Open("PIP:",2000) counts for two and so can be cloned
   by your program.  After allocating a filehandle structure (using the
   AmigaDOS memory conventions), just copy the filehandle from Open()
   into the new structure --- and don't forget to Close() both of them!
   My WShell command shell uses the ConMan PIP: device as its pipe handler.

   Those of you with AmigaDOS 1.3 (but not yet blessed with WShell) will
   appreciate the sly inclusion of the NEWCON: mountlist entry.


   Break Signals.
   Break signals are generated by typing a control-C, D, E, or F and can be
   delivered to any task that has opened, read from, or written to ConMan.
   The break-signal handling in ConMan is much more sophisticated than that
   in the standard CON: handler, and additional improvements have been made
   in V1.3 to eliminate the possibility of signalling a non-existent task.
   ConMan is able to signal a task that has only read from or written to the
   console -- even if it hasn't opened it -- by holding the break event until
   a read or write request arrives.

   In addition to the break signals generated by user input, ConMan will
   send a control-C break to any task that continues to write to the handler
   when it's trying to close.  ConMan is in such a "closing" state after the
   close gadget on a window has been hit, or if it is a PIP: pipe with only
   one open remaining.  This automatic "break-on-write" provides a way of
   propagating a signal back through a series of piped programs.


   Keymapping.
   ConMan supports the Amiga's keymapping facility, which allows you to
   reassign the editing functions to the keys of your choice.  To do this,
   you must first construct a keymap either in assembly language or with
   the help of a keymap editor.  You can then load the keymap using the
   SetMap program on your Workbench disk.  By default SetMap makes a keymap
   global; if you want to use a special keymap from just one CLI, you can
   use the included KeyMap command to define the desired map.  KeyMap with
   no arguments will display a list of the available keymaps.


                              ----- Bugs -----
   All known bugs have been fixed in this release, so you should find it to
   be very reliable.  If you do find a problem, PLEASE report it so I can
   fix it!!

                        ----- Acknowledgements -----
   Special thanks to John Toebes and the Software Distillery for lots of
   great suggestions, to Jeff White for the handsome icons, and to the many
   contributors who made ongoing development and improvements possible.

                              -- Bill Hawes (October 5, 1989)